home *** CD-ROM | disk | FTP | other *** search
/ Gamers Delight 2 / Gamers Delight 2.iso / Aminet / game / role / NetHack_3_1.lha / NetHackDoc / Install.ami < prev    next >
Text File  |  1993-02-02  |  17KB  |  351 lines
  1.  
  2.       Using, Compiling, and Installing Amiga NetHack 3.1
  3.       (or Everything You Never Wanted to Know Before NetHacking)
  4.  
  5.          Last Revision: 12 January 1993 for NetHack 3.1
  6.  
  7.  
  8. I. Introduction
  9.  
  10. I.A. Overview
  11.     Welcome to Amiga NetHack!  If this is your first visit to our fair
  12.     city, you are in for an amazing and dangerous journey; if you have
  13.     visited us before, beware! the city has changed in many strange and
  14.     subtle ways; it has also grown quite a bit.  This missive brings to
  15.     light those mundane tasks which must be dealt with before beginning
  16.     your journey; for those of you who are faced with the task of
  17.     installing the pre-fabricated version of our town, section III
  18.     (Installing Amiga NetHack 3.1) will guide you through the task at
  19.     hand.  If you are ready to visit, the local visitors guide is in
  20.     section II (Using Amiga NetHack 3.1); please also see the general
  21.     guide packaged separately (the file GuideBook).  Finally, for those
  22.     brave souls among you who prefer to scratch-build your own models,
  23.     your guidance is in section IV (Compiling Amiga NetHack 3.1).
  24.     
  25.     To all our visitors, a hearty Welcome! - and please be careful.
  26.  
  27.     [Those responsible for the previous paragraphs have been sacked.  The
  28.     documentation has been completed at great expense in a more traditional
  29.     style. -- The Management]
  30.  
  31. I.B. Getting Help
  32.     If you have questions about strategy, weapons, or monsters, the best
  33.     place to go for help is the Usenet newsgroup rec.games.hack.  If you
  34.     have problems with installation or think you have found a bug in
  35.     the game, please report it by electronic mail to the development
  36.     group at nethack-bugs@linc.cis.upenn.edu, where it will be routed
  37.     to the appropriate person.  Include your configuration, the version of
  38.     NetHack you are playing, and as much specific information as possible.
  39.     As NetHack runs on many different machines, be sure to mention that
  40.     you are playing the Amiga version.  Finally, if you are having trouble
  41.     compiling NetHack, you may use the same address, or, for compiler
  42.     specific problems, send mail to:
  43.         Greg Olson (golson@sundown.sun.com)  for Manx
  44.         Ken Lorber (keni@oasys.dt.navy.mil) for SAS/C, or
  45.         Richard Addison (addison@pollux.usc.edu) for either.
  46.     We do not currently have a contact for the DICE port.
  47.  
  48. I.C. Credits
  49.     Olaf Seibert first ported NetHack 2.3 and 3.0 to the Amiga.  Richard
  50.     Addison, Jochen Erwied, Mark Gooderum, Ken Lorber, Greg Olson, Mike
  51.     Passaretti, and Gregg Wonderly polished and extended the 3.0 and 3.1
  52.     ports.
  53.  
  54.  
  55. II. Using Amiga NetHack 3.1
  56.  
  57. II.A. Sources of Information
  58.     Where to go depends on what you want to find out.  If you want to find
  59.     out about distributing NetHack, read the license (in NetHack:license or
  60.     type ?i during the game).  For an introduction to NetHack, read the
  61.     GuideBook file.  Finally, for information during the game on all kinds
  62.     of things, type ? and select from the menu.
  63.  
  64. II.B. The Amiga NetHack WorkBench Front End
  65.     The Amiga NetHack Front End looks more or less like a WorkBench
  66.     Drawer - and acts the same way.  Games start with double clicks and
  67.     menus provide more detailed control of games and defaults.  On-line
  68.     help is available - just press the help key.
  69.  
  70.     Just as with WorkBench itself, options for games are set using the Info
  71.     menu item to modify Tooltypes.  Most common options can be set more 
  72.     easily using buttons available via Info also.
  73.  
  74.     You can adjust the following using the ToolTypes from the Info command:
  75.  
  76.     * OPTIONS=<options> - Options as available in the NetHack.cnf file.
  77.  
  78.     * HACKDIR=<directory> - Set NetHack working directory to be this
  79.       directory.
  80.  
  81.     * LEVELS=<levels> - Intermediate level saving device/directory.
  82.  
  83.     * PATH=<path> - To search for files such as rumors, help, etc.
  84.  
  85.     * CMDLINE=<args> - Arguments as passed on the CLI command line.
  86.       Note:  only the following flags are valid: n, X, D, and r.
  87.  
  88.     * SCORE <options> - Display the record of scores.  Options as
  89.       available on the CLI command line after a -s flag.
  90.  
  91.     Note that the NetHack.cnf file is read first, then the ToolTypes.  This
  92.     means that the options specified in the NetHack.cnf act as defaults
  93.     which can be overridden by an individual's personal icon's ToolTypes.
  94.     Thus the system oriented entries (HACKDIR, LEVELS, and PATH) should
  95.     generally be set only in NetHack.cnf.  NetHack.cnf should have default
  96.     values for OPTIONS, which will generally be overridden by ToolTypes
  97.     entries.
  98.  
  99.     Also, there is one additional option that may be specified in the
  100.     NetHack.cnf file or on an OPTIONS line: flush.  When enabled, flush
  101.     discards all characters in the queue except the first, which limits
  102.     typeahead accidents.  The default setting is noflush.
  103.  
  104.     Usually, most of the confusing options will be set in the NetHack.cnf
  105.     file once when the game is installed and can be ignored after that.
  106.  
  107. II.C. The Amiga NetHack CLI Front End
  108.     The CLI Front End provides the standard Unix-like command line interface
  109.     to NetHack.  Unlike the Unix front end however, the CLI front end will
  110.     ask if you want to play again before exiting.  See the ManPage file for
  111.     the standard Unix flags for NetHack.  In addition to those flags, Amiga
  112.     NetHack accepts flags -l to force non-interlaced mode and -L to force
  113.     interlaced mode.
  114.  
  115.  
  116. III. Installing Amiga NetHack 3.1
  117.  
  118. III.A. General Installation
  119.     Installation should be easy - basically it consists of putting files
  120.     where they belong and adding assigns to your startup.  If you are
  121.     installing from the official binary distribution, simply unpacking
  122.     each archive in the appropriate directory will put the files in the
  123.     places they belong (note that the archives may have been split
  124.     for distribution).  If you are installing from source, most of this
  125.     work will be done by the time the build is finished.
  126.  
  127.     IF YOU ALREADY HAVE A PREVIOUS VERSION INSTALLED YOU MUST DELETE THE
  128.     OLD SAVE AND BONES FILES - THEY WILL NOT WORK!
  129.  
  130. Will NetHack fit on your machine?
  131.     NetHack 3.1 is large.  NetHack 3.1 is very large.  You will need:
  132.     > Amiga 500, 1000, 2000, 2500, or 3000.  The A600, A1200, and A4000
  133.       should work, but have not been tested.
  134.     > WorkBench 1.3 or 2.04.  WorkBench 1.2 will NOT work; we will NOT
  135.       be fixing that.  WorkBench 2.1 and 3.0 should work but have not been
  136.       tested.
  137.     > At least 2 meg of RAM.  NetHack will NOT run in 1 meg.
  138.     > Mass storage: NetHack will run on one floppy - but it won't be nice.
  139.       Two floppies are almost enough.  A hard drive with over 3 meg of
  140.       free space is recommended.
  141.  
  142. Find space for the files
  143.     Floppy installation:
  144.     Format four disks named:
  145.         NetHack
  146.         HackExe
  147.         NHsave
  148.         NHlevels
  149.     Hard Disk installation:
  150.         cd to wherever you want to install NetHack
  151.     makedir NetHack
  152.     makedir NetHack/save
  153.     makedir NetHack/levels
  154.     In s:User-Sequence (under 2.0 or later) or s:Startup (under 1.3),
  155.     assign NetHack: to the NetHack directory you created above.
  156.     assign HackExe: to the same directory.
  157. Install the files
  158.     Unpack the archives in the directories or onto the disks (you can
  159.     tell what to unpack where by the file names).  Use the table in the
  160.     next section to see where things should end up.  Be sure that the
  161.     file 8 ends up in NetHack:hack/8.
  162.  
  163. Configuration
  164.     Using your favorite text editor, edit NetHack:NetHack.cnf to match
  165.     your system.  Check HackExe:NetHack.dir and be sure that the paths
  166.     are correct.  The HackWB program uses several standard Amiga programs
  167.     that must be installed in their standard places: c:copy, c:rename.
  168.  
  169. III.B. File Location Table
  170.     NetHack:
  171.     A-filla.lev    A-fillb.lev    A-goal.lev    A-locate.lev
  172.     A-start.lev    air.lev        asmodeus.lev    astral.lev
  173.     B-filla.lev    B-fillb.lev    B-goal.lev    B-locate.lev
  174.     B-start.lev    baalz.lev    bigroom.lev    C-filla.lev
  175.     C-fillb.lev    C-goal.lev    C-locate.lev    C-start.lev
  176.     castle.lev    cmdhelp        data        default.icon
  177.     dungeon        E-filla.lev    E-fillb.lev    E-goal.lev
  178.     E-locate.lev    E-start.lev    earth.lev    fakewiz1.lev
  179.     fakewiz2.lev    fire.lev    Guidebook    Guidebook.info
  180.     H-filla.lev    H-fillb.lev    H-goal.lev    H-locate.lev
  181.     H-start.lev    hack/8        hack.font    HackWB
  182.     HackWB.info    HackCli        help        hh
  183.     history        juiblex.lev    K-filla.lev    K-fillb.lev
  184.     K-goal.lev    K-locate.lev    K-start.lev    knox.lev
  185.     license        logfile        ManPage        ManPage.info
  186.     medusa-1.lev    medusa-2.lev    minefill.lev    minetown.lev
  187.     mine_end.lev    NetHack.cnf    NetHack.c01    NetHack.d00
  188.     news        NewGame.info    opthelp        options
  189.     oracle.lev    oracles        orcus.lev    P-filla.lev
  190.     P-fillb.lev    P-goal.lev    P-locate.lev    P-start.lev
  191.     perm        quest.dat    R-filla.lev    R-fillb.lev
  192.     R-goal.lev    R-locate.lev    R-start.lev    ReadMe
  193.     ReadMe.info    record        recover        rumors
  194.     S-filla.lev    S-fillb.lev    S-goal.lev    S-locate.lev
  195.     S-start.lev    sanctum.lev    T-filla.lev    T-fillb.lev
  196.     T-goal.lev    T-locate.lev    T-start.lev    tower1.lev
  197.     tower2.lev    tower3.lev    V-filla.lev    V-fillb.lev
  198.     V-goal.lev    V-locate.lev    V-start.lev    valley.lev
  199.     W-filla.lev    W-fillb.lev    W-goal.lev    W-locate.lev
  200.     W-start.lev    water.lev    wizard1.lev    wizard2.lev
  201.     wizard3.lev    wizhelp
  202.  
  203.     HackExe:
  204.     NetHack.dir
  205.     NetHack.c00
  206.  
  207.  
  208. IV. Compiling Amiga NetHack 3.1
  209.  
  210. IV.A. Compilation Overview
  211.     Compiling NetHack is not very hard - basically you do a little
  212.     configuration and start make.  It does, however, require a good amount
  213.     of disk space - almost 7 meg (and subject to change; more if you are
  214.     not doing the simple compile - more on that later).  It also needs a
  215.     good bit of memory.
  216.  
  217. IV.B. Basic Compilation
  218.     NetHack can be built with SAS/C version 5.10b, Manx/Aztec version 5,
  219.     or the registered version of DICE.  The "official" compiler for NetHack 3.1
  220.     patchlevel 0 is SAS/C 5.10b - we expect to be moving to SAS/C version 6.2
  221.     after it is released (6.0 was not available soon enough to gain our
  222.     confidence for releasing binaries based on it).  The game will compile
  223.     under SAS/C 6.x with small changes.
  224.  
  225. IV.B.1. Introduction to Compiling NetHack
  226.     Before doing any compilation, read the README files distributed
  227.     with the source.  These should familiarize you with the source tree
  228.     layout, and what files are shared with what computers.  Generally,
  229.     everything in the sys/amiga directory is used exclusively by the Amiga.
  230.  
  231.     The makefile (Makefile.ami) is set up to depend upon certain assignments,
  232.     providing the developer with a fairly flexible environment.  See
  233.     makefile.ami for assignment assumptions.
  234.  
  235.     Edit config.h to your liking and system configuration.  The following
  236.     need to be checked:
  237.  
  238.     UNIX - undef
  239.     MACROCPATH - undef
  240.     HACKDIR - define as "NetHack:"
  241.  
  242.     For SAS/C 6.x, in config.h, make sure that '#define NEARDATA' is used
  243.     and not '#define NEARDATA __near'.  The v5 compiler recognizes a
  244.     different syntax than the v6 compiler for this construct. You will
  245.     need to build without __near for now to get around this problem.
  246.  
  247.     At this point, you're almost ready to begin a compile.  Read VERY
  248.     CAREFULLY through the Makefile to familiarize yourself with which
  249.     assignments are assumed.  Otherwise, you're going to get something
  250.     like "Insert NHS: in any drive." requestors.  You will need the
  251.     programs uudecode, flex, and bison.  Be sure the p bit is set in
  252.     the permissions for ifchange.  The first thing Makefile.ami does
  253.     is build a program called 'makedefs', which handles a variety of
  254.     data file generation, and a pair of programs called 'lev_comp' and
  255.     'dgn_comp' which compile the special levels.  Makedefs will then be
  256.     run to create a few files, followed by an alphabetically sorted
  257.     compilation of the entire source tree.  This compilation process
  258.     will compile selected files from the Amiga:, Share:, and NHS:
  259.     directories.  If all goes well, all of the  objects will be linked
  260.     together to form a binary.  After building the main binary, a make
  261.     install will build the auxiliary files including help files, special
  262.     levels, icons, and the font files and will put these files into their
  263.     final positions.  The first make run should be done in OBJ: and the
  264.     make install should be done in NetHack:; for both runs, the makefile
  265.     is Amiga:Makefile.ami.
  266.  
  267.     For SAS/C 6.x: in Makefile.ami, comment out the SAS5 macros and
  268.     uncomment the SAS6 macros.
  269.  
  270.     Note that not all the source is simple C code.  If you are modifying
  271.     lev_comp or dgn_comp you may need bison and/or flex (depending on what
  272.     modifications you are making).  If you wish to modify the Intuition
  273.     windows in HackWB, the (uuencoded) PowerWindows files are provided.  You
  274.     do not need any of these tools to simply build NetHack - all the C output
  275.     files are provided in the source distribution.  Also, the ifchange
  276.     script requires a version of diff that produces standard Unix format
  277.     context diffs for proper operation - the version shipped with SASC
  278.     is not sufficient.
  279.  
  280.     If you do not have bison and flex, copy the files from Share:.  The
  281.     include files go in incl: and the C files go in util:.  If the compile
  282.     fails due to prototype errors for malloc and realloc, try deleting
  283.     the first line of lev_comp.c and dgn_comp.c.
  284.  
  285. IV.B.2. Compiling NetHack with SAS/C version 5
  286.  
  287.     NOTE WELL - Amiga NetHack will be dropping support for SAS/C version 5
  288.     and moving to SAS/C version 6 almost immediately.  Upgrade now!  You
  289.     have been warned.
  290.  
  291.     This version of NetHack was developed with SAS/C 5.10b and SAS/C 6.1.
  292.     Earlier versions of the compiler are known to cause problems - don't
  293.     use them.
  294.  
  295.     A couple of notes and warnings from the SAS/C users on the team:
  296.  
  297.     * Included in the SAS/C port is code for generating a SnapShot.tb
  298.       file upon catching various internal disasters.  That is why the
  299.       -d1 flag is in the makefile.  This adds about 270K to the disk
  300.       image, but it does not increase the run time memory requirements.
  301.           (But note that this is not useful for split binaries - see below.)
  302.  
  303.     * The 5.10b optimizer does not produce correct code for NetHack.
  304.  
  305.     * There are a large number of warnings under SAS/C, which are
  306.       harmless.
  307.  
  308.     * Some versions of flex produce #line statements with the file name
  309.       in quotes: version 5.10b doesn't like this.  For some reason lc tries
  310.       to access this file, which results in a bogus requestor for "Util:
  311.       (yes, there is one quote mark in front of Util:) - select cancel
  312.       and ignore the problem or add -L to the FLEX definition in
  313.       Makefile.ami.  SAS says that this will be fixed in 6.0.
  314.  
  315. IV.B.3. Compiling NetHack with SAS/C version 6
  316.     Very simliar to compiling under version 5 except all the command lines
  317.     are different - see the Makefile.  Also, see the note above about
  318.     NEARDATA.
  319.  
  320. IV.B.4. Compiling NetHack with Manx/Aztec version 5
  321.     The Manx port has not been tested recently and is probably broken.  We
  322.     expect to have it back in shape soon but we welcome context diffs.  As
  323.     of the last check, NetHack required version 5.0B of the compiler.  
  324.  
  325. IV.B.5    Compiling NetHack with the registered version of DICE
  326.     The DICE port was complete at one point but has not been tested in
  327.     several months - it probably will not work as is.  We welcome context
  328.     diffs (or volunteers) to fix it.
  329.  
  330. IV.C. Advanced Compilation
  331.     As mentioned above, NetHack is very large.  There are several
  332.     techniques under development by the Amiga NetHack Team for dealing
  333.     with the situation.  As they are completed, they will be documented
  334.     here.  Before attempting any of them, you MUST do a "normal" build
  335.     as documented above; the techniques described below require the
  336.     auxiliary files from a normal build to form a complete NetHack
  337.     installation.
  338.  
  339. IV.C.1 Splitter
  340.     Splitter addresses two problems with NetHack: first, the long startup
  341.     time of the game, and second, the size of the binary (which will not fit
  342.     on a single disk).  See the file split/split.doc for information on
  343.     splitter.  The normal install target in Makefile.ami will build the
  344.     split version of NetHack as part of the normal install process; the
  345.     front ends will run from either the normal version (HackExe:NetHack) or,
  346.     preferably, from the split version (NetHack.c#?  NetHack.d#?) - the
  347.     decision is based on the presence (or absence) of HackExe:NetHack.dir.
  348.     Note that the contents of NetHack.dir after a build will generally not
  349.     be the correct contents for a floppy based system.
  350.    
  351.